No event has occurred. Also called a “null event.”
The doNothing event indicates that the event queue is empty and that no event has occurred. This occurs only when PollSystem returns with a value of false.
Programming Considerations
``````````````````````````
• If your application does “background processing,” that is, it performs
an on-going process while it is waiting for events, it should perform
“one cycle” of its background process each time it receives a
doNothing event. A single cycle of your application’s background
process should take no longer than 1/60 of a second. See the
SetNullTime routine to set the interval at which your application
receives doNothing events.
• Picture buttons with the “repeating events” option turned on may
produce doNothing events if your application calls PollSystem more
frequently than the button changes its value. This will cause no ill
Request to activate an inactive window that belongs to your application.
The request to activate an inactive window is made in response to the user clicking anywhere on an inactive window that belongs to your application. However, there is one exception. If the user clicks in an inactive window’s title bar while holding the Command key, the window is dragged without being activated.
Programming Considerations
``````````````````````````
• A window can be activated by using the ActivateWindow procedure.
• If the active window has an active editing field, you may want to
validate the edited text before allowing the user to activate another
window. If this is the case, use GetFieldString to obtain a copy of
the edited text, then your application can check the string for
errors. If an error is detected, display an appropriate alert box and
ignore the doChgWindow event. If no error is detected, call the
SaveFieldString procedure to save the edited text as the field’s
string, then activate the required window.
• If your application decides not to allow the user to activate a
window, it should display an appropriate alert box to explain why.
• The doChgWindow event will never occur when a modal window is active,
or when the watch cursor is displayed since other windows belonging to
your application cannot be clicked.
• A doChgWindow event does not occur if the user clicks on a tool bar or
floating palettes.
• If your application is running under Finder (System 6 or prior), a
doChgWindow event will not occur when the user [1] clicks a desk
accessory from an active window, [2] clicks a desk accessory from
another active desk accessory, or [3] clicks the previously active
window from an active desk accessory. These are all handled
A window’s contents need to be refreshed (redrawn) after Tools Plus has refreshed its own objects.
Your application must respond to this event. The doRefresh event occurs when a window is completely or partially obscured, then becomes uncovered. Tools Plus takes care of redrawing buttons, scroll bars, editing fields, list boxes, pop-up menus, picture buttons and custom controls. Your application must take care of refreshing anything else, such as icons, pictures, lines, or text that it may have put in the window. When your application receives this event, Tools Plus will have already drawn its objects.
When a doRefresh event is reported, the window’s “update region” defines the exact area that needs to be refreshed, excluding the objects drawn by Tools Plus (buttons, scroll bars, editing fields, list boxes, pop-up menus, picture buttons and custom controls). Although you can redraw everything in the window, the actual drawing is limited to the parts of the window that are visible and which need refreshing (Tools Plus changes the window’s update region to exclude its own objects).
Your application can ignore the doRefresh event if you have chosen to do all the necessary drawing in response to a doPreRefresh event, or if the only objects in the window are drawn by Tools Plus (buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls).
Programming Considerations
``````````````````````````
• If your application did not put anything in the window except buttons,
picture buttons, scroll bars, editing fields, list boxes, pop-up
menus, and custom controls, it can ignore this event.
• If your application responds to a doRefresh event, it should do so in
the following manner:
CurrentWindow(Poll.Window); {Make the affected window the }
{ current grafPort. }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
{ the area that needs }
{ refreshing (includes all }
{ monitors). }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
begin { in which the window appears. }
BeginUpdateScreen(theScreen); {Drawing area reduced to the }
{ specified screen. }
{ …insert your color-dependent drawing code here… }
EndUpdateScreen; {End the drawing for this }
{ monitor, and restore the }
{ window’s visible (drawing) }
end; { region. }
{ …insert your color-independent drawing code here… }
EndUpdate(WindowPointer(Poll.Window)); {End the update for the window }
CurrentWindowReset; {Reset the current window to be }
{ the same as the active window}
{ (optional command). }
• BeginUpdate temporarily sets the window’s visRgn (visible region where
drawing occurs) to the intersection of the visRgn and updateRgn
(region requiring updating). This effectively restricts drawing to
the area that needs updating. Tools Plus removes its own objects
(buttons, scroll bars, editing fields, list boxes, pop-up menus,
picture buttons and custom controls) from the updateRgn, so you don’t
have to worry about accidentally drawing over those objects
• It is possible that several windows will need to be refreshed
simultaneously if, if for instance, a closing window exposed three
windows behind it. PollSystem reports a single doRefresh event each
time it is called in the event loop, one event for each window that
needs refreshing.
• Unlike ordinary Macintosh applications, a doRefresh event is not
generated when a window is first opened.
• A doRefresh event is not generated for desk accessories, the Dialog
Manager’s dialogs, alerts, or Dynamic Alerts. These events are
handled automatically.
• When responding to a doRefresh event, your application should limit
itself to activities that pertain only to refreshing the specified
window. Do not create or modify user interface elements, open, close,
or move windows.
• See the doPreRefresh event if your application needs to refresh all or
part of the window before Tools Plus refreshes its own objects
(buttons, picture buttons, scroll bars, editing fields, list boxes,
A window’s contents may be refreshed (redrawn) before Tools Plus refreshes its own objects.
Most applications will ignore this event. A doPreRefresh event is reported before each doRefresh event (which occurs when a window is completely or partially obscured, then becomes uncovered and needs to be redrawn). The doPreRefresh event lets your application draw or display objects before Tools Plus draws its own objects (buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls).
An example of the doPreRefresh event’s usefulness is if your application displays a picture as a window’s background. When your application receives a doPreRefresh event, it can draw the background picture only. The next time your application calls PollSystem, Tools Plus will refresh all its own objects and report a doRefresh event for your application to process.
When a doPreRefresh event is reported, the window’s “update region” defines the exact area that needs to be refreshed. Although you can redraw everything in the window, the actual drawing is limited to the parts of the window that are visible and which need refreshing.
Programming Considerations
``````````````````````````
• If your application did not put anything in the window except buttons,
picture buttons, scroll bars, editing fields, list boxes, pop-up
menus, and custom controls, it should ignore the doPreRefresh event.
• If your application responds to a doPreRefresh event, it should do so
in the following manner:
CurrentWindow(Poll.Window); {Make the affected window the }
{ current grafPort. }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
{ the area that needs }
{ refreshing (includes all }
{ monitors). }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
begin { in which the window appears. }
BeginUpdateScreen(theScreen); {Drawing area reduced to the }
{ specified screen. }
{ …insert your color-dependent drawing code here… }
EndUpdateScreen; {End the drawing for this }
{ monitor, and restore the }
{ window’s visible (drawing) }
end; { region. }
{ …insert your color-independent drawing code here… }
EndUpdate(WindowPointer(Poll.Window)); {End the update for the window }
CurrentWindowReset; {Reset the current window to be }
{ the same as the active window}
{ (optional command). }
• BeginUpdate temporarily sets the window’s visRgn (visible region where
drawing occurs) to the intersection of the visRgn and updateRgn
(region requiring updating). This effectively restricts drawing to
the area that needs updating. The affected area may include Tools
Plus objects which are automatically refreshed the next time
PollSystem is called.
• It is possible that several windows will need to be refreshed
simultaneously if, for instance, a closing window exposed three
windows behind it. PollSystem reports a single doPreRefresh event
(followed by a doRefresh event) each time it is called in the event
loop, one event for each window that needs refreshing.
• Unlike ordinary Macintosh applications, a doPreRefresh event is not
generated when a window is first opened.
• A doPreRefresh event is not generated for desk accessories, the Dialog
Manager’s dialogs, alerts, or Dynamic Alerts. These events are
handled automatically.
• When responding to a doPreRefresh event, your application should limit
itself to activities that pertain only to refreshing the specified
window. Do not create or modify user interface elements, open, close,
The request to close the active window is made in response to the user clicking inside the window’s “close” box. This has the same effect as choosing the File menu’s Close item.
Programming Considerations
``````````````````````````
• A window is closed by using the WindowClose procedure.
• If the window has an active editing field, you may want to validate
its edited text before allowing the user to close the window. If this
is the case, use GetFieldString to obtain a copy of the edited text,
then your application can check the string for errors. If an error is
detected, display an appropriate alert box and ignore the doGoAway
event. If no error is detected, call the SaveFieldString procedure to
save the edited text as the field’s string, then close the required
window.
• If any changes have been made in the window’s data, your application
should display an appropriate alert box and ask the user if changes
should be saved. The options should be Yes, No, and Cancel, the last
of which would ignore the doGoAway event.
• The doGoAway event will never occur when the watch cursor is
displayed, since the close box cannot be clicked.
• A doGoAway event is not generated when the user clicks a desk
accessory’s close box. The desk accessory is closed automatically.
• You may want to consider hiding a window (with the WindowDisplay
routine) instead of closing it in situations where a window is opened
and closed frequently, such as a floating palette or tool bar. Hiding
and showing a window preserves the window’s setting and location, and
is much faster than opening a window and recreating the user interface
elements. However, hiding a window does not release the memory
consumed by the objects in the window (such as picture buttons, list
The doButton event reports that the user has clicked a button in the active window. This includes push buttons, check boxes and radio buttons. The doButton event is also reported if the active window has a default push-button, and the user pressed the Return or Enter key to invoke the default. If this is the case, the window’s default button will already have been “flashed” as if the user had clicked it.
Programming Considerations
``````````````````````````
• If the user clicked a check box, use SelectButton to reverse the check
box’s selection (i.e. select or deselect it).
• If the user clicked a radio button, use SelectButton to select the
radio button, and to deselect the other buttons in the radio button’s
group.
• This event will never occur when the watch cursor is displayed, since
buttons cannot be clicked. The exception is if the WatchCursorButtons
procedure has been used to allow the watch cursor to click push-
buttons.
• If your application responds to double-clicks in radio buttons and
Poll.Button.DoubleClick is true, consider the event to mean “click
button and OK,” in which case the default button should be flashed and
the appropriate action taken.
• A doButton event is not generated when the user clicks buttons in a
dialog box, alert box, or desk accessory. These events are handled
Indicator that the user selected a pull-down or hierarchical menu item.
The user selected a pull-down or hierarchical menu by either clicking in the menu bar and selecting an item, or by typing a Command key equivalent for a menu item.
Programming Considerations
``````````````````````````
• The menu’s name in the menu bar is automatically highlighted (white
letters on black background) when the user makes a menu selection.
Your application must call MenuHilite(0) to remove the highlighting
when it is finished with its process.
• If a hierarchical menu item is selected, the name of its ultimate
parent menu is highlighted in the menu bar (white letters on black
background). Your application must call MenuHilite(0) to remove the
highlighting when it is finished with its process. If a Command key
equivalent for a hierarchical menu item is typed, and the hierarchical
menu is not ultimately attached to a pull-down menu, a doKeyDown or
doAutoKey event is reported instead (as though the hierarchical menu
did not exist).
• This event will never occur when a modal window is active, or when the
watch cursor is displayed since the menu cannot be clicked and Command
key equivalents are ignored.
• If the active window has an active editing field, PollSystem will
process the Edit menu’s Undo, Cut, Copy, Paste, and Clear commands
automatically. These selections will not generate doMenu events.
• A doMenu event is not generated when the user selects desk accessory
menus. These selections are handled automatically.
Indicator that the user held down a key, and it is repeating.
The user has pressed down a key on the keyboard or numeric pad, and the key is repeating. The key cannot be processed internally by Tools Plus. In most cases, this event should be treated identically to a doKeyDown event. Each doAutoKey event will follow a doKeyDown of the same sort, so your application may want to make some repeating Command key sequences illegal.
Programming Considerations
``````````````````````````
• This event is generated only if the key can not be processed
internally by Tools Plus.
• Command key sequences that are equivalents to menu items generate
doMenu events.
• If a Command key equivalent for a hierarchical menu item is typed, and
the hierarchical menu is not ultimately attached to a pull-down menu,
a doKeyDown or doAutoKey event is reported instead (as though the
hierarchical menu did not exist).
• The Modifiers field tells your application if the repeating key down
event was a Command key sequence. All Command key sequences that are
not menu equivalents are returned to your application as doKeyDown or
doAutoKey events. If your application gets such a Command key
sequence, it should carry out the appropriate action, or beep the user
if the Command key sequence is illegal.
• If Return or Enter are typed and held down when the active window has
a default button, a doButton event is reported for the default button.
• If an active editing field exists on the active window, repeating keys
will affect the field and will not generate events. This applies even
if the field’s length is limited, or if Return has been disallowed in
a field.
• If Tab is typed and the window contains an active editing field, it
indicates that the user wants to tab to the next field. Shift-Tab
indicates tabbing to the previous field. You may want to validate a
field’s edited text before allowing the user to tab to the new field.
If this is the case, use GetFieldString to obtain a copy of the
edited text, then your application can check the string for errors.
If an error is detected, display an appropriate alert box and ignore
the doKeyDown event. If no error is detected, call the
SaveFieldString procedure to save the edited text as the field’s
string, then activate the new field by using the ActivateField
procedure.
• A Return key is reported only if the window does not have a default
button or active field.
• If Enter is typed, it usually indicates that the user wants to enter
the screen’s data. This is the same process that is carried out by
clicking an OK button. See “Tab” above, regarding validating and
saving a field’s edited text. An Enter key is reported only if the
window does not have a default button. The repeating Enter key may be
considered illegal because a doKeyDown event will report the first
Enter, after which your application should have acted accordingly. An
Enter key is reported only if the window does not have a default
button.
• When the watch cursor is displayed, the only doAutoKey event that will
be reported is a Command-., which is the user’s request to halt a
lengthy process. Other doAutoKey events are discarded.
• If the active window has an active editing field, PollSystem
automatically processes the Command key equivalents for the Edit
menu’s Undo, Cut, Copy, and Paste commands. These selections do not
generate events.
• There are two situations where several keys produce the same key
character: the Clear and Escape keys, and the F1 through F15 keys. In
these cases, use the key code to differentiate the keys. Constants
are provided for these key characters and key codes.
• A doAutoKey event is not generated when the user types in a desk
accessory. These key strokes are handled automatically.
The user has released a key on the keyboard or numeric pad, and the key cannot be processed internally by Tools Plus. Normally the Macintosh does not report doKeyUp events nor do applications typically respond to them. See “Key-Up Events” in the Designing Your Application chapter for details on the SetEventMask procedure.
Programming Considerations
``````````````````````````
• This event is generated only if your application has used the
SetEventMask procedure to make the Macintosh respond to key-up events,
and if the active window does not have an active editing field.
• Tools Plus and desk accessories do not require key-up events, and
therefore ignore them.
• There are two situations where several keys produce the same key
character: the Clear and Escape keys, and the F1 through F15 keys. In
these cases, use the key code to differentiate the keys. Constants
are provided for these key characters and key codes.
• When the watch cursor is displayed, all doKeyUp events are discarded
Indicator that the user clicked in an inactive editing field.
When the user clicks in an inactive editing field in the active window, it indicates that the user has finished working with the currently active field and wants to start working with the one that was clicked. Tools Plus automatically supports the full range of Macintosh user interface options for editing fields, including (but not limited to):
• clicking in the field, thereby placing an insertion point
• dragging across characters to create a selection
• double-clicking a word to select it
Programming Considerations
``````````````````````````
• The ClickInField procedure is used to process a user’s click in an
inactive editing field. It could be in the same window that the user
is working in, or it could be in a tool bar or floating palette
• If an editing field is active when you receive a doClickField event,
you may want to validate its edited text before allowing the user to
click to the new field. If this is the case, use GetFieldString to
obtain a copy of the edited text, then your application can check the
string for errors. If an error is detected, display an appropriate
alert box and ignore the doClickField event. If no error is detected,
call the SaveFieldString procedure to save the edited text as the
field’s string, then call the ClickInField procedure to process the
user’s click in the new field.
• Between the time that the doClickField event is reported and the
ClickInField procedure is used as a response, observe the following
rules:
• do not call PollSystem
• do not open or close any windows, including alerts and dialogs
• do not hide or show any windows
• do not activate any windows.
If these rules are not observed, ClickInField will do nothing and the
user’s click is ignored.
• An event will not occur if the user clicks in an editing field that is
already active.
• This event will never occur when the watch cursor is displayed, since
editing fields cannot be clicked.
• A doClickField event is not generated when the user clicks in a desk
accessory’s editing fields. The process is handled automatically.
The doScrollBar event reports that the user has clicked somewhere in a scroll bar. The scroll bar has 5 parts: up button, down button, “page up” region, “page down” region, and the thumb. In all cases, your application should respond to the scroll bar event by scrolling the window’s contents (or portion thereof) and drawing any parts that have been newly revealed due to scrolling.
Programming Considerations
``````````````````````````
• If the scroll bar’s thumb was moved, your application can obtain the
current value of the scroll bar by calling GetScrollBarVal. By using
this value, your application can determine how much to scroll.
• If the scroll bar’s up button, down button, “page up” region, or “page
down” region was clicked, your application must scroll the window by
the correct amount, then change the scroll bar’s value by using
SetScrollBarVal.
• If the up arrow or “page up” region is clicked, subtract the correct
amount from the current value. If the down arrow or “page down”
region is clicked, add the correct amount to the current value.
• If the user holds the mouse button down in the up arrow, “page up”
region, down arrow, or “page down” region, PollSystem returns a single
doScrollBar event each time PollSystem is called. Your application
doesn’t have to be aware of this, but it is nice to know that scroll
bar events will not pile up in the queue.
• If the user moves the scroll bar’s thumb and returns it to its
original place during the same drag, an event is not generated.
• This event will never occur when the watch cursor is displayed, since
scroll bars cannot be clicked.
• Scroll bars that are part of a list box are handled automatically.
• A doScrollBar event is not generated when the user clicks scroll bars
in a dialog box or desk accessory. These events are handled
